home *** CD-ROM | disk | FTP | other *** search
/ AGA Toolkit '97 / The AGA Toolkit '97.iso / programming / c / smc2cweb / docs / c2cweb.txt < prev    next >
Encoding:
Text File  |  1996-09-07  |  16.8 KB  |  473 lines
  1.  
  2. This is the c2cweb package Version 1.4 (20-Aug-1994)
  3. =====================================================
  4.  
  5. Copyright (C) 1994 Werner Lemberg
  6.  
  7. [see below for a German introduction]
  8.  
  9.  
  10. c2cweb will transform plain C or C++ code into a CWEB file to get a pretty
  11. formatted output. A modified CWEAVE (which transforms the CWEB file into a
  12. TeX file, see below) is included also.
  13.  
  14. Some c2cweb highlights:
  15.  
  16.     variables and function names in italics
  17.     reserved words (int, char, return etc.) in bold face
  18.     strings in typewriter type
  19.     comments in typwriter type or roman
  20.     an index(!) of all variables, constants, function names etc.
  21.     each function gets a section
  22.  
  23.     and more
  24.  
  25.  
  26. c2cweb.zip contains the following files:
  27.  
  28.     c2cweb.txt          this file
  29.     history.txt         the history file
  30.     diff.txt            GNU diff between Ver. 1.4 and Ver. 1.3
  31.     Makefile            a makefile to compile c2cweb for UNIX, OS/2, and DOS
  32.     c2cweb.def          definition file (needed for compiling under OS/2 only)
  33.     COPYING             the GNU Copying License
  34.     c2cweb.w            a CWEB file of the program
  35.                           you should say
  36.                              make documentation (using this package's CWEAVE)
  37.                           to produce a TeX-output
  38.     c2cweb.dvi          the final .dvi-file
  39.     c2cweb.exe          an executable for DOS and OS/2
  40.     compiler.w          compiler dependent formatting commands
  41.                         (an output of c2cweb reads this file)
  42.     c2cweb.ger          a small german `package' to demonstrate national
  43.                         language support
  44.     example.h
  45.     example.c           a C code example with inserted c2cweb control commands
  46.     emx.exe             the emx DOS-extender (ver. 0.8h) (for VCPI)
  47.     rsx.exe             the rsx DOS-extender (rev. 4beta, 32bit) (for DPMI)
  48.     emx.dll             the emx runtime library for OS/2 (ver 0.8h)
  49.     cweb/cweave.exe     a modified executable (for DOS and OS/2) of
  50.                         CWEAVE Ver. 3.2 with three important new features:
  51.                           o the switch +a causes CWEAVE to produce a different
  52.                             output format, basically
  53.  
  54.                               if(a)
  55.                                  {bla bla bla...
  56.                                  }
  57.  
  58.                             instead of
  59.  
  60.                               if(a) {
  61.                                   bla bla bla...
  62.                               }
  63.  
  64.                           o the switch +i causes CWEAVE to append () after a
  65.                             function name in the index (this makes only sense
  66.                             if all names are unique)
  67.                           o the #define statement handling was basically
  68.                             enhanced to allow macros with parameters
  69.     cweb/cweave.w       this is the original CWEAVE source file of Levy's
  70.                         CWEB package ver 3.2 (July 1994)
  71.     cweb/cweave.ch      the change file for cweave.w
  72.     cweb/common.h       this is needed to build CWEAVE
  73.                         (slightly different from the original)
  74.     cweb/common.w       taken unaltered from CWEB 3.2
  75.     cweb/common.ch      change file for common.w
  76.     cweb/Makefile       Makefile for CWEAVE (UNIX, OS/2, and DOS)
  77.     cweb/cweave.def     definition file (needed for compiling under OS/2 only)
  78.     cweb/cwebmac.ori    the standard cwebmac.tex file (slightly modified)
  79.     cweb/cwebmac.tex    alternative format file
  80.     cweb/cwebmaca.tex   this alternative format file is read by TeX if you use
  81.                         the +a switch; similar to cwebmac.tex
  82.     cweb/prod-alt.w     this file is an include file of cweave.ch; it
  83.                         contains the alternative syntax rules of CWEAVE if the
  84.                         switch a is on
  85.  
  86. You should get the original CWEB package for further documentation; it contains
  87. change files for different operating systems also.
  88.  
  89.  
  90. Copying
  91. -------
  92.  
  93. This program is free software; you can redistribute it and/or modify it under
  94. the terms of the GNU General Public License version 2 as published by the
  95. Free Software Foundation.
  96.  
  97. This program is distributed in the hope that it will be useful, but
  98. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  99. or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  100. for more details.
  101.  
  102. You should have received a copy of the GNU General Public License along with
  103. this program; if not, write to the Free Software Foundation, Inc.,
  104. 675 Mass Ave, Cambridge, MA 02139, USA.
  105.  
  106.  
  107. Installation
  108. ------------
  109.  
  110. The c2cweb executable should be in the path.
  111.  
  112. The CWEAVE executable should also be in the path; it needs the file compiler.w
  113. (use the environment variable CWEBINPUTS to set the path).
  114.  
  115. c2cweb.ger, cwebmac.tex and cwebmaca.tex must be found by TeX (the path is
  116. usually controlled by the TEXINPUT environment variable).
  117.  
  118. DOS and WINDOWS user must assure that emx.exe and rsx.exe can be found (either
  119. in the path or set with the EMX and RSX environment variables).
  120.  
  121. OS/2 user must assure that emx.dll and rsx.exe can be found (either in the path
  122. or set with the EMX and RSX environment variables).
  123.  
  124.  
  125. Remarks for UNIX systems user
  126. -----------------------------
  127.  
  128. Because of the many different UNIX implementations, no executables are
  129. included. The programs should compile without great problems if you use the
  130. gcc compiler, the GNU C library and gnumake; you should say
  131.  
  132.     make unix
  133.  
  134. in the c2cweb and cweb directories to build the executables.
  135.  
  136.  
  137. Both makefiles need CTANGLE (included in the CWEB package, the original host is
  138. labrea.stanford.edu; the current version is 3.2 dated July 1994).
  139.  
  140.  
  141. How to use
  142. ----------
  143.  
  144. The only change the user has to do normally is to insert /*@@*/ starting an
  145. empty line outside of a comment or string before the first function block
  146. (normally main(){ ... }) in the C code. After this command c2cweb writes each
  147. function block into a section. Before /*@@*/ all stuff is written into a
  148. (possibly large) section. If you want to structure this further or if you have
  149. structure definitions between functions, use /*@*/ to start a new section
  150. without starting the function block algorithm (and of course /*@@*/ before the
  151. next function).
  152. The function algorithm simply counts paired braces; if none are open, a new
  153. section will begin.
  154. The file example.c has these control codes inserted already.
  155.  
  156.  
  157. The syntax is
  158.  
  159.     c2cweb [switches] csourcefile(s) | @responsefile(s)
  160.  
  161. The possible switches are:
  162.  
  163. -v:
  164.  
  165. all comments are written in typewriter type. You will need this if you have
  166. already formatted your comments, for example
  167.  
  168.             /********************/
  169.             /*    example.c     */
  170.             /********************/.
  171.  
  172. -t value:
  173.  
  174. all tabs will be expanded, and the -t switch defines the tab length (default
  175. value is 4).
  176.  
  177. -l:
  178.  
  179. causes all linefeeds inside of C text to be output explicitly by inserting
  180. @/ (a CWEB control code) at the end of each code line.
  181.  
  182. -o directory:
  183.  
  184. sets the output directory which must exist already.
  185.  
  186. -b "titlestring":
  187.  
  188. defines a title with the titlestring enclosed in double quotes. This string
  189. will be passed directly to \TeX.
  190.  
  191. -1:
  192.  
  193. one-sided output (i.e. left header is the same as right header).
  194.  
  195.  
  196. The last steps are calling CWEAVE with the transformed master file and then
  197. calling TeX to get a printable .dvi-file.
  198.  
  199.  
  200. An example:
  201.  
  202.     your input files are
  203.         header1.h, header2.h, file1.c, file2.c, file3.c
  204.  
  205.     you must call then
  206.         c2cweb [options] header*.h file*.c
  207.  
  208.     to get the *.*w files. c2cweb will now process your files and tell you
  209.     which file is the input file for CWEAVE (we'll assume file3.cw).
  210.  
  211.     After calling
  212.         cweave [options] file3.cw
  213.  
  214.     you get a .tex file (and some additional auxiliary files) which should be
  215.     processed further by PLAIN TeX (LaTeX is not supported):
  216.  
  217.         tex file3[.tex]
  218.  
  219.  
  220. Please read the `Hints and Tricks' section about enhancements and limitations
  221. of c2cweb in the file c2cweb.w (say `make documentation' to build the .dvi
  222. file).
  223.  
  224.  
  225. Author
  226. ------
  227.  
  228. Werner Lemberg (a7621gac@awiuni11.bitnet)
  229.  
  230. Please report any errors, comments or suggestions to this email-address.
  231.  
  232. N.B.: If you like this program, send me a postcard !
  233.  
  234.     Werner Lemberg
  235.     Goldschlagstr. 52/14
  236.     A-1150 Vienna/Austria
  237.  
  238.  
  239.  
  240. --------------------------------------------------------------------------------
  241.  
  242.  
  243.  
  244. c2cweb Paket Version 1.4 (20-Aug-1994)
  245. =======================================
  246.  
  247. Copyright (C) 1994 Werner Lemberg
  248.  
  249.  
  250. c2cweb verwandelt gew”hnlichen C - oder C++ - Quellcode in eine CWEB-Datei,
  251. um einen gut formatierten Ausdruck zu erhalten. Dieses Paket enth„lt auáerdem
  252. eine modifizierte Version von CWEAVE (welche die CWEB-Datei in eine TeX-Datei
  253. transformiert).
  254.  
  255. Besonderheiten u.a.:
  256.  
  257.     Variablen und Funktionsnamen in Kursivschrift
  258.     reservierte W”rter (int, char, return etc.) in Fettschrift
  259.     Strings in Schreibmaschinenschrift
  260.     Kommentare in Normal- oder Schreibmaschinenschrift
  261.     ein Index(!) aller Variablen, Konstanten, Funktionsnamen etc.
  262.     jede Funktion fllt einen eigenen Abschnitt
  263.  
  264.  
  265. c2cweb.zip enth„lt folgende Dateien:
  266.  
  267.     c2cweb.txt          diese Datei
  268.     history.txt         Entstehungsgeschichte von c2cweb
  269.     diff.txt            GNU diff zwischen Ver. 1.4 und Ver. 1.3
  270.     Makefile            ein Makefile fr c2cweb (UNIX, OS/2 und DOS)
  271.     c2cweb.def          Definitionsdatei (wird nur fr die Kompilation unter
  272.                           OS/2 gebraucht)
  273.     COPYING             GNU Kopierlizenz
  274.     c2cweb.w            die CWEB-Realisation dieses Programms
  275.                           Um eine TeX .dvi-Datei zu erhalten sollte man
  276.                             make documentation
  277.                           eingeben (mit der CWEAVE-Version dieses Pakets)
  278.     c2cweb.dvi          die finale .dvi-Datei
  279.     c2cweb.exe          ausfhrbares Programm fr DOS und OS/2
  280.     compiler.w          Compiler-abh„ngige Formatierbefehle
  281.                         (von c2cweb erzeugte Dateien inkludieren diese Datei)
  282.     c2cweb.ger          ein kleines Deutsch-`Paket', um die Untersttzung von
  283.                         nichtenglischen Sprachen zu demonstrieren.
  284.     example.h
  285.     example.c           ein C-Code-Beispiel mit bereits eingefgten c2cweb-
  286.                         Kontrollbefehlen
  287.     emx.exe             emx DOS-Extender (Ver. 0.8h) (fr VCPI)
  288.     rsx.exe             rsx DOS-Extender (Rev. 4beta, 32bit) (fr DPMI)
  289.     emx.dll             emx Laufzeit-Bibliothek fr OS/2 (Ver. 0.8h)
  290.     cweb/cweave.exe     eine modifizierte Version von CWEAVE Version 3.2
  291.                         (fr DOS und OS/2) mit drei wichtigen neuen
  292.                         Eigenschaften:
  293.                           o mit der Option +a formatiert CWEAVE den Quellcode
  294.                             anders, und zwar im Prinzip
  295.  
  296.                               if(a)
  297.                                  {bla bla bla...
  298.                                  }
  299.  
  300.                             anstelle von
  301.  
  302.                               if(a) {
  303.                                 bla bla bla...
  304.                               }
  305.  
  306.                           o die Option +i veranlaát CWEAVE, jedem
  307.                             Funktionsnamen () im Index anzuh„ngen (nur
  308.                             sinnvoll, wenn alle Namen eindeutig sind)
  309.                           o die Behandlung von Pr„prozessorbefehlen (#define
  310.                             etc.) wurde entscheidend verbessert, um Makros
  311.                             mit Parametern zu erm”glichen
  312.     cweb/cweave.w       die originale CWEAVE Quelldatei aus Levy's CWEB-Paket
  313.                         Version 3.2 (Juli 1994)
  314.     cweb/cweave.ch      Change-Datei fr cweave.w
  315.     cweb/common.h       wird ben”tigt fr die Kompilation von cweave.exe
  316.                         (Original wurde etwas modifiziert)
  317.     cweb/common.w       unver„ndert von CWEB 3.2 bernommen
  318.     cweb/common.ch      Change-Datei fr common.w
  319.     cweb/Makefile       Make-Datei fr CWEAVE (UNIX, OS/2 und DOS)
  320.     cweb/cweave.def     Definitionsfile (wird nur fr die Kompilation unter
  321.                           OS/2 gebraucht)
  322.     cweb/cwebmac.ori    ursprngliche cwebmac.tex-Datei (leicht ver„ndert)
  323.     cweb/cwebmac.tex    alternative Formatdatei
  324.     cweb/cwebmaca.tex   diese alternative Formatdatei wird von TeX gelesen,
  325.                         wenn die +a-Option angegeben ist; sonst gleich zu
  326.                         cwebmac.tex
  327.     cweb/prod-alt.w     diese Datei ist eine Include-Datei von cweave.ch;
  328.                         sie enth„lt die alternativen Syntaxregeln, falls
  329.                         Option +a verwendet wird
  330.  
  331. Es ist empfehlenswert, sich das originale CWEB-Paket zu besorgen, welches
  332. weitere Dokumentation enth„lt. Auáerdem sind Change-Dateien fr andere
  333. Betriebssysteme enthalten.
  334.  
  335.  
  336. Installation
  337. ------------
  338.  
  339. c2cweb (c2cweb.exe fr DOS und OS/2 Benutzer) sollte im Pfad sein.
  340.  
  341. CWEAVE (cweave.exe fr DOS und OS/2 Benutzer) sollte auch im Pfad sein; es
  342. braucht die Datei compiler.w (die Umgebungsvariable CWEBINPUTS setzt den Pfad).
  343.  
  344. TeX muá die Dateien c2cweb.ger, cwebmac.tex und cwebmaca.tex finden k”nnen (der
  345. Pfad wird normalerweise von der TEXINPUT-Umgebungsvariablen kontrolliert).
  346.  
  347. DOS und WINDOWS Bentzer mssen sicherstellen, daá emx.exe und rsx.exe gefunden
  348. werden k”nnen (entweder im Pfad oder durch die Umgebungsvariablen EMX und RSX
  349. bestimmt).
  350.  
  351. OS/2 Bentzer mssen sicherstellen, daá emx.dll und rsx.exe gefunden werden
  352. k”nnen (entweder im Pfad oder durch die Umgebungsvariablen EMX und RSX
  353. bestimmt).
  354.  
  355.  
  356. Bemerkungen fr UNIX Benutzer
  357. -----------------------------
  358.  
  359. Aufgrund der vielen verschiedenen UNIX-Systeme sind keine ausfhrbaren Dateien
  360. inkludiert. Die Programme sollten ohne gr”áere Probleme kompilierbar sein, wenn
  361. gcc, die GNU C-Bibliothek und gnumake verwendet wird.
  362.  
  363.     make unix
  364.  
  365. im c2cweb- und cweb-Verzeichnis erstellt die ausfhrbaren Dateien.
  366.  
  367. Beide Make-Dateien ben”tigen CTANGLE (aus dem CWEB-Paket; der ursprngliche
  368. Host ist labrea.stanford.edu; die aktuelle Version is 3.2 datiert Juli 1994).
  369.  
  370.  
  371. Verwendung
  372. ----------
  373.  
  374. Die einzige Ver„nderung, die der Anwender normalerweise machen muá, ist das
  375. Einfgen von /*@@*/ am Anfang einer leeren Zeile auáerhalb eines Kommentars
  376. oder Strings vor dem ersten Funktionsblock (das ist in der Regel main(){ ...})
  377. im C-Quellcode. Nach diesem Befehl erzeugt c2cweb fr jede Funktion einen
  378. eigenen Abschnitt. Vor /*@@*/ wird alles in eine einzige (u.U. groáe) Sektion
  379. geschrieben. Will man solche Abschnitte zus„tzlich strukturieren oder hat man
  380. Struktur-Definitionen zwischen Funktionen, sollte man /*@*/ verwenden, um einen
  381. neuen Abschnitt zu beginnen ohne den Funktionsalgorithmus einzuschalten (und
  382. natrlich /*@@*/ vor der n„chsten Funktion).
  383. Der Funktionsalgorithmus z„hlt einfach paarweise geschwungene Klammern; falls
  384. keine mehr offen, wird ein neuer Abschnitt begonnen.
  385. In der Beispieldatei example.c sind diese Kontrollcodes bereits enthalten.
  386.  
  387.  
  388. Aufruf:
  389.  
  390.     c2cweb [Optionen] C-Quelldatei(en) | @Response-Datei(en)
  391.  
  392. Folgende Optionen sind m”glich:
  393.  
  394. -v:
  395.  
  396. alle Kommentare werden in Schreibmaschinenschrift ausgegeben. Dieser Schalter
  397. ist notwendig, falls die Kommentare bereits formatiert sind, zum Beispiel
  398.  
  399.             /********************/
  400.             /*    example.c     */
  401.             /********************/.
  402.  
  403. -t Wert:
  404.  
  405. all Tabulator-Stopps werden expandiert; -t Wert definiert die Tabulatorweite
  406. (Grundeinstellung: Wert=4).
  407.  
  408. -l:
  409.  
  410. Zeilenumbrche in der Eingabe innerhalb von C-Text bleiben in der Ausgabe
  411. erhalten durch explizites Anh„ngen von @/ (einem CWEB Kontrollcode) an jede
  412. Code-Zeile.
  413.  
  414. -o Verzeichnis
  415.  
  416. definiert das Ausgabeverzeichis (muá bereits existieren).
  417.  
  418. -b "Titel":
  419.  
  420. definiert einen Titel (in doppelten Anfhrungszeichen). Dieser String wird
  421. direkt an TeX weitergegeben.
  422.  
  423. -1:
  424.  
  425. einseitige Ausgabe (d.h., linker Seitenkopf wird dem rechten Seitenkopf
  426. gleichgesetzt).
  427.  
  428.  
  429. Die letzten Schritte sind das Aufrufen von CWEAVE mit der transformierten
  430. Hauptdatei und danach der Aufruf von TeX, um eine druckf„hige .dvi-Datei zu
  431. erhalten.
  432.  
  433.  
  434. Ein Beispiel:
  435.  
  436.     die Eingabedateien:
  437.         header1.h, header2.h, file1.c, file2.c, file3.c
  438.  
  439.     Man muá jetzt
  440.         c2cweb [Optionen] header*.h file*.c
  441.  
  442.     aufrufen, um die *.*w-Dateien zu erhalten. c2cweb bearbeitet jetzt alle
  443.     Eingabedateien und teilt mit, welche Datei die Eingabedatei fr CWEAVE ist
  444.     (hier im Beispiel sei es file3.cw).
  445.  
  446.     Nach dem Aufruf
  447.         cweave [Optionen] file3.cw
  448.  
  449.     erh„lt man eine .tex-Datei (und einige zus„tzliche Hilfsdateien), die
  450.     mit PLAIN TeX weiterverarbeitet werden muá (LaTeX wird nicht untersttzt):
  451.  
  452.         tex file3[.tex]
  453.  
  454.  
  455. Im Abschnitt `Hints and Tricks' in der Datei c2cweb.w werden weitere
  456. Verbesserungen und Beschr„nkungen von c2cweb beschrieben (der Aufruf
  457. `make documentation' erzeugt die .dvi-Datei).
  458.  
  459.  
  460. Autor
  461. -----
  462.  
  463. Werner Lemberg (a7621gac@univie.ac.at)
  464.  
  465. Bitte alle Fehler, Kommentare oder Bemerkungen an obige email-Adresse schicken.
  466.  
  467. N.B.: Wenn Ihnen das Programm gef„llt, schicken Sie mir doch eine Postkarte !
  468.  
  469.     Werner Lemberg
  470.     Goldschlagstr. 52/14
  471.     A-1150 Vienna/Austria
  472.  
  473.